.--------------------------------------------------------------------- 
.- template for "unfinished" html pages (called .htm files here).
.- This is the source file for the pyNMS Manual. It is the source file
.- for building the Manual, using htmlpp.
.-
.- $Id: Manual.htm,v 1.1 2005/07/25 21:25:16 kdart Exp $
.--------------------------------------------------------------------- 
.-  The BASE variable tells htmlpp what to call the output files. 
.- 
.define BASE      Manual
.--------------------------------------------------------------------- 
.- suppress informational messages.
.- include macro definitions.
.include macros.def 
.- set some flags:
.define SILENT 1
.-
.- UNDERCONSTRUCTION will cause the inclusion of an "under construction" bar.
.define UNDERCONSTRUCTION 1
.-
.- If HEADERLOGO is not 0 (zero), build a header graphic block.
.define HEADERLOGO 1
.block headerlogo
<TABLE border=0 cellpadding=0 cellspacing=0 width="70%">
<TR><TD Align=left >
.IMAGE cosine-qa.jpg 
</TD>
<TD Align=left ><FONT size="+3" color="blue" face="Helvetica;Arial;Sans-serif">pyNMS Online Manual</FONT></TD>
</TR>
</TABLE><BR>
.end
.- define searchpage to the name of a page with a search dialog, if required.
.define SEARCHPAGE ""
.-
.- manual.def defines the "look and feel" of this manual set.
.include pynmsmanual.def
.- standard URL list
.include links.def
.-
.- don't put h5's and lower in the table of contents to make it cleaner.
.ignore header 5
.--------------------------------------------------------------------- 
.page Python Network Management System
 
<H1>$(TITLE)</H1> 
 
.-  This file builds a table of contents for the current document, 
.-  i.e. all the pages that result from this original text file. 
.- 
.include contents.def 

.--------------------------------------------------------------------- 
.page Overview
.H2 $(TITLE)

<P>
The Python Network Management System, or pyNMS, is a suite of $(*python) modules
that make it easy to write various network management tools. The collection of modules here may also be used for other things.
</P>

<P>Currently, the best source of information is in the Python source code. The
source code has comments and embedded documentation ("docstrings"). The 
$(*module_html="module documentation") is generated by a program from the
docstrings, and is pretty good reference material. </P>

<h2>Notes</h2>
<P>The <A HREF="TODO.html">current TO DO list</A>.</P>

.page Design
.H2 $(TITLE)
<P>

</P>

.page Installation
.H2 $(TITLE)
<P>There are several ways to install and use pyNMS. It may be installed for
individual use in a private locatation, or installed for shared usage in a
public location such as a file server, or on a multi-user machine.  A
source tarball is available by $(*pynmsftp="anonymous ftp"). </P>

.H3 Installing from the distribution

<P>First, Get the $(*pynmsftp="latest pyNMS") snapshot (a gzipped tar file).</P>

<P>Before doing anything else, be sure to set an environment variable called
 to the location where you will be untarring the pyNMS distribution.
More detailed instructions are located in the <A HREF="INSTALL">INSTALL</A>
file.</P>

<pre>
$ PYNMS_HOME=$HOME/PYNMS
$ export PYNMS_HOME
</pre>

<P>Inside the tarball is an install script called install.py. This will perform
all necessary installation steps. Note that to compile the C module requires
having gcc and gmake installed on the system. </P>

<pre>
cd $PYNMS_HOME/doc
./install.py
</pre>

.H3 Dependencies
<P>While PYNMS comes with a number of included modules, there are still some
additional software that PYNMS depends on that must be installed seperately.
Briefly, your system must have the following:</P>

.h4 Essential Packages
<ul>
    <li>$(*python=Python) 2.2 - the python language interpreter.
    <li>$(*htmlpp="htmlpp") - HTML PreProcessor. Used to generate this documentation.
</ul>

.h4 Optional Packages
<ul>
    <li>$(*gtk=GTK) - GUI toolkit for GUI elements
    <li>$(*pygtk=PyGTK) - Python language bindings for the GTK and Gnome toolkit
    <li>$(*pyimaging=Imaging) Libarary - Python imaging library
    <li>$(*numeric=Numeric) library (numpy) - provides mathematical functions and large arrays for data analysis.
</ul>


.page Configuration
.H2 $(TITLE)

<P>pyNMS has a layered configuration system. There is a global
configuration file, a user configuration file, and local configuration
files.  Each file has a number of sections, plus a DEFAULT section.</P>

<P>The configuration class is located in the module
<i>$PYNMS_HOME/lib/nmsconfig.py</i>. This module extends the standard python
class called ConfigParser.  The syntax of this file looks a lot like the old
Microsoft Windows .ini files. That is, it is divided into sections with section
names in square brackets ([]), and name-value pairs each seperated by an equal sign
(=). </P>

<P>For example:</P>

<pre>
[SectionName]
name = value
another_name = another_value
...
</pre>

<P>These configuration files behave a bit different than real .ini files,
however. There is a special section called [DEFAULT] where attribute values
will be taken from if they do not exist in the named section. </P>

<P>The sections below provide a brief description of each configuration
file. For more detailed information, refer to the nmsconfig module
documentation, and the qatest module documentation.
</P>

<h4>Global Configuration</h4>
<P>The global file is <i>$PYNMS_HOME/etc/pynms.conf</i>. All scripts, test suites,
and users will get configuration information from here by default.</P>

<h4>User Configuration</h4>
<P>
The users configuration file is <i>$HOME/.pynmsrc</i>. If it exists than
configuration values will be taken from here, overriding equivalent ones found
in the global configuration file.  </P>

<h4>Test/Local Configuration</h4>
<P>
When a test or other script is run, the API also looks in the current
directory for a <i>pynms.conf</i> file. Entries in this file take precedence
over the other two. 
</P>

<h4>Custom Configuration files</h4>
<P>
In addition to the above configuration files, each test may have its own
configuration file. You can read these by passing a list of file names to
<code>nmsconfig.get_config()</code> function.
</P>

.page Usage
.H2 $(TITLE)

.page Examples
.H2 $(TITLE)

.page Selected Module Description
.H2 $(TITLE)
<P>This section describes some of the more useful and important modules in
the pyNMS libarary more thoroughly than the reference documentation does.</P>
<P>Some of the more noteworthy modules are:</P>

<ul>
    <li>SNMP
    <li>SMI
    <li>Devices
    <li>nmsconfig
    <li>qatest
    <li>ipv4
    <li>Console
    <li>POM
    <li>HTML
    <li>NMSUtil
</ul>


<h3>nmsconfig module</h3>
<P>
</P>


.page Selected Utility Description
.H2 $(TITLE)

<h3>acons</h3>
<P>The acons script can be used to access a device serial console via a terminal server.
</P>
<P>acons [&lt;devname&gt;] [&lt;scriptfile&gt;]</P>

<P>Connect to a configured devices console port via a terminal server. If
&lt;devname&gt; is not given then your configured DEFAULT device will be used.
If &lt;scriptfile&gt; is given then it should be a specially formated
send/expect script that will be used to interact with the device.
Otherwise an interactive session will start. The session uses a
pure-python implementation of the TELNET protocol.</P>



.page References
.H2 $(TITLE)
<P>
</P>


